Skip to content

spec(FIX-2241): a task's midway question reaches its filer as a message - #3994

Merged
jhoffner merged 4 commits into
mainfrom
spec/FIX-2241
Oct 27, 2026
Merged

jhoffner merged 4 commits into
mainfrom
spec/FIX-2241

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Spec for FIX-2241, a child of epic FIX-2070. Retained at specs/issues/FIX-2241/ (SPEC.md · DECISIONS.md). Merging it is the approval; implementation starts after the merge.

Reviewers: this is a direction check (bar and two-round budget in docs/contributing/orchestration.md). It adds no code.

Who feels it

Someone who… Today After
files work for a worker, a worker's model Hears nothing when its task asks a question midway. It finds out only if it happens to read the row with getTask Hears it on onMessageReceived, in the session that filed the task, as a message from the task's worker naming the task and the question. It may answer it with updateTask({ id, question, message }) or leave it to the user
filed a task that was routed to a workstream Hears nothing Hears it the same way, told that the user answers it from the Inbox. Its own answer is still refused question_is_the_users
filed a coding task Hears nothing when the coding run's question ends the run Hears it the same way: the coding run's question is a midway question too
is the user Sees one Inbox item for the question Sees the same one item. The filer's answer, if it comes first, closes it; the message is never a second item (PR-3)
runs a ring of workers that is out of budget n/a The question still reaches the filer: the server's question costs no budget (epic ER-6)

The goal, and how we'll know it's met

When a task a worker filed asks a question midway, by its model or by its coding run, the filer hears it on onMessageReceived in the session that filed the task, once, at no cost to the budget, and can answer it there with a steer that lets the task go on, while the user's one Inbox item stays the only stop.

Is it the right goal?
The real need The issue: "a question a task asks midway reaches its filer as a message from the task's session … The filer may answer it with a steer unless the task is routed, or leave it to the user." Concept rule 11 and the epic's leg e
Smaller, and rejected "The askQuestion tool sends a message." A coding run's question (harness-manager's ask step) would stay silent
Bigger, and not this issue's Delivery that survives a crash after the message row (FIX-2240)
Not done if A coding run's question doesn't reach the filer · the filer's model has to call getTask to learn the question or its id · a question is told twice · the question spends budget, or is refused at a spent one · a routed task's filer is told it may answer · the message opens a second Inbox item · a crash and a replay of the asking turn loses or doubles the message · the filer's answer doesn't let the task go on, on the same attempt
flowchart LR
  A["Shift Manager desk Lab · real model · file-backed host"] --> J["leg j1 · desk.front files for desk.asker, told the answer up front"]
  J --> Q["the asker's task asks midway"]
  Q -->|"a received item in desk.front's conversation · its own turn steers"| P["PASS · completed, attempt 1, no user line between"]
  A --> K["leg j1b · the coder's run asks"]
  K -->|"a received item in the filing session"| P
  C["control · no-question-message"] -.-> Q
  Q -.->|"under the control"| F["must FAIL · j1:filer-hears"]
Loading

Goal check: goals/shift-manager/every-stop-is-one-inbox-item/, leg j1 amended in place, real model, 3 of 3; full signal, input, anti-game and controls in SPEC.md.

Sign off

The goal, at that size: every midway question, the coding run's included, reaches its filer once, free, and the filer's steer lets the task go on. If wrong: a filer that could have answered leaves it to the user.

The debt: flat. Adds one optional hook on the board's delivery declaration (DeclaredDelivery.questionAsked) and one budget-exempt send through sendMessage's server path. If wrong: a second way to tell a filer grows beside the task notice.

No decision cards: the epic decided the model, and FIX-2133 the answer. Open: none. The engineering calls are in DECISIONS.md → Decided, not asked.

Feature · orchestration, workforce, harness-manager (tests only) + docs · small · 1 PR, after FIX-2238's (stacked on it while it is open) · epic FIX-2070


Generated by Claude Code

@jhoffner jhoffner self-assigned this Oct 27, 2026
@vercel

vercel Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 27, 2026 9:25pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 27, 2026 9:25pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 27, 2026 9:25pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 27, 2026

Copy link
Copy Markdown

FIX-2241

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-27T21:26:27.272278Z b7798d4 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect coherence check (head c337e6a): no fork.

This builds in one direction with what's in flight:

  • It keeps FIX-2058/FIX-2133's model: the hold on the row stays the record, the Inbox item stays the one stop, and the filer's answer is FIX-2133's updateTask steer. The retired park notice doesn't come back.
  • It uses FIX-2238's send server path and onMessageReceived (the 2026-10-27 rename), the epic's ER-2 landing rule and ER-6 budget exemption, and FIX-1989's dedupe by id. It adds no second delivery path or registry.
  • spec(epic): phased workflows, a feature a person can follow phase by phase (FIX-2092) #3970 FIX-2092's held phase steps are a different meaning of hold (pending until released, not a question), so "plan steps are never held" doesn't conflict with them. Only open midway question holds send.

One small thing to note so it doesn't get renamed twice: #3985 hands the four meanings of hold and updateTask's question field to FIX-2183. This spec adds the new name DeclaredDelivery.questionAsked and server text that teaches updateTask({ id, question, message }). Please add a line to Notes for the implementer saying both are in FIX-2183's scope, so its codemod and the server-written text change together. That doesn't block the direction.

— FSD Architect

Copy link
Copy Markdown
Collaborator Author

Added in 313060b: DECISIONS.md → Notes for the implementer now says DeclaredDelivery.questionAsked and the server text that teaches updateTask({ id, question, message }) are in FIX-2183's scope, so its codemod renames the hook and updates that text in one change.


Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (direction check, read-only)

Verdict: the shape is right. askMidway is the real convergence point (askQuestion and harness-manager/src/ask-step.ts both call it), and a declared hook on DeclaredDelivery keeps Layer 1 free of any message concept. I'd keep it. Findings below are for the implementer to fold or note; none changes the approach.

# Finding Why it matters Suggestion
1 SPEC and DECISIONS disagree on when the hook fires. SPEC's table says "after a successful ask it calls the board's hook". DECISIONS says a crash-replay's ask is declined (lease gone) and the hook must still send from the row's stored holds. On main, askMidway returns {ok:false} for a declined ask, and the ask-step.ts caller maps lost-claim to "superseded". A hook gated on asked.ok would never fire on the replay path, which is the exact path "once, a replay included" exists for. Say in SPEC which one it is. If the hook fires on decline-with-open-holds, put that decision in one place inside askMidway. Don't let each caller re-derive it. Add a CI test of the replay (ask declined, holds present, one send).
2 askMidway already returns holds and already has ctx.runOnce replay protection. The spec adds a second source of truth: re-reading the committed row's open midway holds. The comment on askMidway says a durable replay "gets the first ask's answer back". The row-read only earns its place for the crash window between the hold write and the runOnce record. That is real, but narrower than the spec presents. Keep the row read, but scope it in the text to that window. Make it one small openMidwayHolds(row) helper next to askMidway. Use asked.holds on the normal path and fall back to the row only when the ask was declined. That is less to review than "always read the row".
3 sendQuestionToFiler must not be a third way to resolve the filer. The spec says "the row's filer session (Task.filer)". Workforce already resolves the filer and its flow through filerResolver plus conversationDelivery.address, including the legacy-filer and workstream-to-coordinator cases. The send needs a session and a flow, not just a session id. A second resolver would drift from the notice path (BP-030 legacy rows, routed tasks whose filer is a coordinator). State in SPEC that the hook reuses address and filerResolver, and that no filer resolves through the hook means no send.
4 The "a waiting filer hears it at once" claim has no evidence and no test. DECISIONS calls it a read of resume-wait-gate.ts and settles with "No POC". It is the premise that retired the first draft's D1. It is the one claim that decides whether a filer blocked in waitForTask hears the question at all. A wrong premise silently turns this into the dropped D1. The goal's Lab leg has desk.front end its turn and does not cover a waiting filer. Run settle-claim on it, or add a model-free CI test with a filer parked on a wait and a question asked. Otherwise it stays unverified (BP-003).
5 The goal check grows a small issue. Amended j1 plus a new workstream plus a model-filed eng.coder task plus j1b, and four controls. ask-tool-only duplicates what the CI test pinning both callers into askMidway already catches. j1b needs the Lab to gain a model-filed coder task, which today's legs don't have. Keep j1 (real model, the filer's steer lets the task go on) and the no-question-message control. Consider a model-free test for the coder path, and drop ask-tool-only unless the j1b leg stays. The routed-text check also looks coverable in CI.
6 Message text duplicates tool-surface knowledge. The server writes updateTask({ id, question, message }) and the Inbox wording itself, separately from answerQuestion's question_is_the_users refusal text. Two places now describe how a filer may answer. Rename the tool or change who may answer and one goes stale. Build the text from one helper beside answerQuestion's rules (midway, not routed), so routed versus unrouted wording and the refusal share a predicate.

Refactor opportunities that fit this PR (and only these):

  • A single openMidwayHolds(row) predicate shared by askMidway's fallback and answerQuestion's midway check (hold.midway !== true || row.target … ). Both currently spell the same rule.
  • Nothing else. The DeclaredDelivery hook is a clean extension point and I'd not restructure the delivery module around it.

Dependency note: sendMessage's server path and onMessageReceived are FIX-2238's and are not on main yet, so none of the send side could be checked against code. The stack order in DECISIONS is correct. Re-check finding 1 against FIX-2238's actual send signature when this is implemented.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Confirmed at 313060b: the Renames note in DECISIONS.md puts DeclaredDelivery.questionAsked and the updateTask({ id, question, message }) server text in FIX-2183's scope. That resolves my note, and the coherence check stays at no fork.

— FSD Architect

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c337e6a098

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread specs/issues/FIX-2241/DECISIONS.md Resolved

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify review (spec-only)

Verdict: The chosen shape is the right one given FIX-2070 (message path, ER-6 exemption, Layer 1 must not name messages). Converging on askMidway + an optional DeclaredDelivery hook filled by conversationDelivery → sendWorkerMessage reuses the FIX-2238 send path and avoids duplicating harness vs askQuestion paths. The alternatives the spec already drops (tool-only send, park notice, workforce-only wiring, structured about on the payload) would be simpler locally and wrong globally.

I do not see a materially cleaner architecture than “one hook, one send.” What I do see is spec surface that could be trimmed and a few implementer traps worth folding into SPEC so DECISIONS is not the only place the hard cases live.

Where complexity is justified

Piece Why it stays
DeclaredDelivery.questionAsked Same declaration object as onUndeliverable; no second registry; orchestration-only boards stay silent.
Row-based “once” + message id dedupe runOnce can skip the ask write on replay while holds remain; delivery cannot be gated only on askMidway returning { ok: true }.
One message per hold Matches one question id per received item and j1 signals; batching would be a different product contract.

Simplification opportunities (optional, not direction forks)

  1. Elevate replay into SPEC “What changes.” Today the happy-path diagram reads like “after successful ask → hook.” DECISIONS already says: re-read committed row / open midway holds when the ask is declined on replay. One sentence in SPEC would cut the risk of a wrong first implementation without changing the design.

  2. Trim j1 Lab scope. New legs, workstream, model-filed coder task, and several controls overlap what model-free workforce / harness-manager tests already pin (both ask paths, budget, routed copy). Keeping j1 focused on filer-hears + filer-answers-own and leaving j1b / routed / budget primarily in CI would shrink goal churn and flaky model legs while preserving the “not done if” list.

  3. Hook signature. (ctx, row, holds) may duplicate data on the row after re-read; (ctx, row) with holds derived inside sendQuestionToFiler is a smaller public type if you want less API ceremony (minor).

  4. Document DeclaredDelivery as more than endings. The type is mentally “notice delivery”; questionAsked is a parallel lifecycle. A short comment in the orchestration type doc (at implementation time) helps board authors; no need to split the type unless readability becomes painful.

  5. Budget exemption scope. ER-6 says the server question is exempt; be explicit in DECISIONS or implementer notes that exemption includes per-request send cap (and hop reservation), not only the 6-message chain — so a multi-hold ask does not fail FIX-2238’s per-turn limit.

  6. Sender-side idempotency (implementation). Receiver dedupe fixes correctness, not cost; pairing deterministic q:<taskId>:<holdId> with per-hold runOnce or log upsert avoids replay re-running full dispatch. Worth a line in “Notes for the implementer” if you want perf parity with the “once” story.

  7. Multi-hold sends. Worst case is sequential sends per hold (bounded by existing steer limits). sendQuestionToFiler should resolve filer/roster once per row, not per hold — implementer note only.

Alternatives considered (still worse)

  • Hardcode send in askMidway without a board hook: breaks Layer 1 / orchestration-only boards.
  • Workforce-only after each caller: two paths + package coupling; misses replay-from-row.
  • Third-party package: nothing off-the-shelf fits FSD’s task hold + session landing + budget seam.

Approval stance

Direction is approve-worthy for a spec PR: debt table’s “flat” claim holds. I’m leaving COMMENT rather than APPROVE so the optional trims above stay visible; none of them require re-gating the epic model.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2241/SPEC.md Resolved
Comment thread specs/issues/FIX-2241/SPEC.md Resolved
Comment thread specs/issues/FIX-2241/SPEC.md Resolved
Comment thread specs/issues/FIX-2241/SPEC.md Resolved
Comment thread specs/issues/FIX-2241/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2241/DECISIONS.md Resolved
@jhoffner jhoffner added the spec label Oct 27, 2026
@jhoffner
jhoffner merged commit 0d70bce into main Oct 27, 2026
13 checks passed
@jhoffner
jhoffner deleted the spec/FIX-2241 branch October 27, 2026 21:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants